app/components/terminal-parts/welcome.ts (1)

9-12: Incomplete JSDoc adds no value.

The JSDoc has an empty description and @param term lacks any explanation. Either complete it with meaningful documentation or remove it entirely.

📝 Suggested complete JSDoc

-/**
- *
- * `@param` term
- */
+/**
+ * Displays the welcome message and ASCII art in the terminal.
+ * `@param` term - The terminal instance to write the welcome output to.
+ */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/components/terminal-parts/welcome.ts` around lines 9 - 12, The JSDoc
block above the function that accepts the parameter "term" is empty and should
be either removed or replaced with a concise doc comment: add a brief
description of what the function does, a clear `@param` term line describing the
parameter's expected type and role (e.g., terminal instance or DOM element used
to render output), and an `@returns` tag if the function returns a value;
alternatively delete the entire JSDoc if no documentation is needed. Target the
JSDoc immediately preceding the function that takes "term" (the function in this
file that uses the term parameter) and ensure the comment accurately reflects
the function signature and behavior.

app/components/terminal-parts/agent-command.ts (1)

16-29: These JSDoc blocks are still placeholders.

They only restate parameter names, so they add maintenance cost without documenting behavior. Either describe the newline normalization / command contract here, or drop the blocks and rely on the existing type signatures.

As per coding guidelines, "Apply KISS (Keep It Simple) - prefer simple solutions over clever ones" and "Apply YAGNI - don't build for hypothetical future needs."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/components/terminal-parts/agent-command.ts` around lines 16 - 29, The
JSDoc blocks for formatForTerminal (and the surrounding terminal-related
functions) are placeholders that only restate parameter names; either remove the
empty JSDoc comments or replace them with a concise, accurate description of
behavior — e.g., for formatForTerminal state that it normalizes tabs to two
spaces and normalizes newlines to CRLF ("\r\n") for terminal compatibility and
describe the expected input/return contract — and ensure the comment is attached
to the function name formatForTerminal (and the subsequent agent terminal
functions) so the codebase contains meaningful, minimal docs rather than
redundant parameter lists.

app/components/terminal-parts/commands.ts (1)

4-6: Remove placeholder JSDoc or make it meaningful.

This block is empty and adds noise; either delete it or document intent/return shape.

♻️ Suggested cleanup

-/**
- *
- */
 export function createStaticCommands() {

As per coding guidelines, "Apply KISS (Keep It Simple) - prefer simple solutions over clever ones."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/components/terminal-parts/commands.ts` around lines 4 - 6, Remove the
empty placeholder JSDoc block at the top of the module (the empty /** ... */
comment in app/components/terminal-parts/commands.ts) or replace it with a
concise meaningful comment describing the module's purpose and exported shapes
(e.g., what key functions/commands return). Keep it short and precise to satisfy
KISS—either delete the block entirely or document intent/return shapes for the
module's exported symbols.

app/components/lite-terminal/input-handler.ts (1)

186-188: Empty JSDoc block on private method adds noise.

The empty JSDoc block for scrollCursorIntoView provides no information. For private methods, either add a meaningful description or omit the JSDoc entirely.

📝 Suggested fix

-  /**
-   *
-   */
   private scrollCursorIntoView(): void {

Or add a description:

-  /**
-   *
-   */
+  /** Scrolls the terminal cursor element into view */
   private scrollCursorIntoView(): void {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/components/lite-terminal/input-handler.ts` around lines 186 - 188, The
empty JSDoc above the private method scrollCursorIntoView adds noise; either
remove the entire empty comment block or replace it with a concise description
of what scrollCursorIntoView does (and document any parameters/return value if
applicable) so the JSDoc is meaningful—locate the private method named
scrollCursorIntoView in input-handler.ts and either delete the /** */ block or
add a one-line summary and param/return tags matching the method signature.

lib/sandbox/createSnapshotSandbox.ts (1)

5-9: JSDoc comment is incomplete.

The parameters lack descriptions. Documenting the fallback behavior would be particularly valuable for this function.

📝 Suggested improvement

-/**
- *
- * `@param` bearerToken
- * `@param` agentDataDir
- */
+/**
+ * Retrieves an existing sandbox from a snapshot, or creates a fresh one if unavailable.
+ *
+ * `@param` bearerToken - Authentication token for the Recoup API
+ * `@param` agentDataDir - Directory containing agent data to initialize fresh sandboxes
+ * `@returns` A Sandbox instance, either restored from snapshot or newly created
+ */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/sandbox/createSnapshotSandbox.ts` around lines 5 - 9, Add full JSDoc for
the createSnapshotSandbox function: document each parameter (bearerToken: string
— what it represents and when it can be omitted or empty; agentDataDir: string —
path where agent data is stored and its default/fallback if not provided),
describe return type and any thrown errors, and explicitly state the fallback
behavior (e.g., what directory is used or how bearerToken is
sourced/fallbacked). Reference the createSnapshotSandbox function and its
parameters bearerToken and agentDataDir so reviewers can verify the docs match
implementation and edge cases.

app/api/agent/new/route.ts (1)

5-8: JSDoc comment is incomplete.

Same pattern as other files - parameter listed without description.

📝 Suggested improvement

-/**
- *
- * `@param` req
- */
+/**
+ * Creates a new agent session with a fresh sandbox environment.
+ *
+ * `@param` req - The incoming request with Authorization header and messages
+ */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/agent/new/route.ts` around lines 5 - 8, The JSDoc above the handler
is incomplete — update the comment to describe the function's purpose and its
parameters/return: add a brief description for the req parameter (e.g., type,
expected shape or fields used), document the return value (e.g., Response or
JSON payload), and include any thrown errors or side effects; target the JSDoc
block that currently only lists "@param req" in app/api/agent/new/route.ts so
callers and maintainers can understand what the handler expects and returns.

app/components/terminal-parts/markdown.ts (1)

13-14: JSDoc parameter lacks description.

The @param text annotation would be more useful with a description explaining what kind of text is expected (e.g., markdown-formatted string).

📝 Suggested improvement

  * Preserves the actual characters but wraps them in ANSI escape sequences.
- *
- * `@param` text
+ *
+ * `@param` text - The markdown-formatted text to apply terminal styling to
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/components/terminal-parts/markdown.ts` around lines 13 - 14, Update the
JSDoc for the function in app/components/terminal-parts/markdown.ts by adding a
descriptive sentence to the `@param` text annotation (e.g., "text -
markdown-formatted string to be rendered" or similar) so callers know the
expected input format and purpose; locate the JSDoc block that currently
contains "@param text" and replace it with a concise description referencing the
markdown-formatted input used by the function that processes or renders the
markdown (the parameter named text).

lib/agent/createAgentResponse.ts (1)

8-13: JSDoc comment is incomplete.

The JSDoc block lists parameter names but lacks descriptions, return type documentation, and a function description. This provides minimal value over no documentation at all.

📝 Suggested improvement

-/**
- *
- * `@param` sandbox
- * `@param` messages
- * `@param` bearerToken
- */
+/**
+ * Creates a streaming agent response using the provided sandbox environment.
+ *
+ * `@param` sandbox - The Vercel sandbox instance to execute commands in
+ * `@param` messages - Array of conversation messages to process
+ * `@param` bearerToken - Authentication token for saving snapshots
+ * `@returns` A streaming Response object
+ */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/agent/createAgentResponse.ts` around lines 8 - 13, The JSDoc for the
createAgentResponse function is incomplete; update the comment block above
createAgentResponse to include a one-line function description, descriptive
`@param` tags for sandbox, messages, and bearerToken (including expected types and
whether optional), and an `@returns` tag describing the returned value/type (and
any promise/async behavior). Also document any thrown errors or side effects
(e.g., network calls) if applicable so callers know what to expect.

lib/agent/handleAgentRequest.ts (1)

6-10: JSDoc comment is incomplete.

Same issue as other files - the JSDoc block lists parameters without descriptions. Consider adding meaningful documentation or removing the empty block.

📝 Suggested improvement

-/**
- *
- * `@param` req
- * `@param` createSandbox
- */
+/**
+ * Handles an incoming agent request by validating auth and delegating to the agent response creator.
+ *
+ * `@param` req - The incoming HTTP request with Authorization header and messages body
+ * `@param` createSandbox - Factory function to create a sandbox instance
+ * `@returns` A streaming Response from the agent
+ */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/agent/handleAgentRequest.ts` around lines 6 - 10, Update the incomplete
JSDoc for the handleAgentRequest function by either removing the empty block or
adding meaningful descriptions for the parameters and return value: document the
req parameter (type and purpose), the createSandbox parameter (what it
does/expected type), and the function's return value or thrown errors; locate
the JSDoc immediately above the handleAgentRequest function in
lib/agent/handleAgentRequest.ts and ensure the annotations (`@param` req, `@param`
createSandbox, and `@returns` or `@throws`) accurately describe expected types and
behavior.

app/api/fs/route.ts (1)

90-93: Empty JSDoc block adds no value.

The JSDoc block for GET is completely empty with no description or documentation. Either add meaningful documentation or remove the empty block entirely.

📝 Suggested fix

-/**
- *
- */
+/**
+ * Returns all text files from the agent data directory as a JSON map.
+ */
 export async function GET() {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/fs/route.ts` around lines 90 - 93, The empty JSDoc block above the
exported GET function is noise; either delete the empty /** */ block or replace
it with a concise description of what GET does (inputs, output shape, status
codes) so the route handler GET is documented; update the comment immediately
above the GET declaration accordingly.

lib/sandbox/readSourceFiles.ts (1)

5-9: JSDoc comment is incomplete.

The parameters dir and baseDir lack descriptions explaining their purpose. The optional nature of baseDir and its relationship to dir should be documented.

📝 Suggested improvement

-/**
- *
- * `@param` dir
- * `@param` baseDir
- */
+/**
+ * Recursively reads all source files from a directory, excluding node_modules and .git.
+ *
+ * `@param` dir - The directory to read files from
+ * `@param` baseDir - Base directory for computing relative paths (defaults to dir)
+ * `@returns` Array of file objects with sandbox-relative paths and content buffers
+ */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/sandbox/readSourceFiles.ts` around lines 5 - 9, The JSDoc for
readSourceFiles is incomplete: add descriptive `@param` tags for dir and baseDir
(noting baseDir is optional) and explain their relationship (e.g., dir is the
path to scan for source files and baseDir, if provided, is used to compute
relative paths or as the root for normalization); update the function-level
comment above readSourceFiles to clearly document return value and optional
parameters so callers understand how baseDir alters the produced paths.

app/md/[[...path]]/route.ts (1)

20-33: SRP guideline violation: two exported functions in one file.
generateStaticParams and GET are both exported from this module. Please refactor to one exported function per file, or add an explicit exception for this framework-specific route file to keep guideline enforcement consistent.

As per coding guidelines, **/*.{js,ts,jsx,tsx}: Apply SRP (Single Responsibility Principle) - one exported function per file.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/md/`[[...path]]/route.ts around lines 20 - 33, This file exports both
generateStaticParams and GET which violates the SRP rule; fix by moving one
export into its own module or add an explicit rule exception for this framework
route file: either extract generateStaticParams into a separate file (exporting
it from there and updating any imports/route config) or keep both but add a
clear file-level exception comment (or disable the specific linter rule) so the
linter knows this route file is allowed to export both; reference the functions
generateStaticParams and GET when making the change so you update the correct
symbols.